package nr.co.mhgames.polyanim.loader;

import java.io.File;
import java.io.InputStream;
import java.io.OutputStream;

import nr.co.mhgames.polyanim.Animation;

/**
 * Interface for the different PolyAnim animation loaders. Implement this to
 * provide new loaders. Note that loader in this case performs I/O both ways:
 * reading (loading) and writing (saving).
 * 
 * @author Mika Halttunen
 */
public interface AnimationLoader {

	/**
	 * Read a PolyAnim animation from the given file and return the animation,
	 * or <code>null</code> if the file couldn't be loaded properly.
	 * 
	 * @param file
	 *            File name of the animation
	 * @return Animation instance
	 * @throws Exception
	 *             Thrown if anything fails
	 */
	public Animation readAnimation(File file) throws Exception;

	/** @see readAnimation(File file) */
	public Animation readAnimation(String file) throws Exception;

	/**
	 * Read a PolyAnim animation from the given input stream and return the
	 * animation, or <code>null</code> if the animation couldn't be loaded
	 * properly.
	 * 
	 * @param input
	 *            Input stream
	 * @return Animation instance
	 * @throws Exception
	 *             Thrown if anything fails
	 */
	public Animation readAnimation(InputStream input) throws Exception;


	/**
	 * Write the given PolyAnim animation to the specified file.
	 * 
	 * @param animation
	 *            Animation instance to write
	 * @param file
	 *            File name
	 * @throws Exception
	 *             Thrown if anything fails
	 */
	public void writeAnimation(Animation animation, File file) throws Exception;

	/** @see writeAnimation(Animation animation, File file) */
	public void writeAnimation(Animation animation, String file) throws Exception;

	/**
	 * Write the given PolyAnim animation to the specified output stream.
	 * 
	 * @param animation
	 *            Animation instance to write
	 * @param output
	 *            Output stream
	 * @throws Exception
	 *             Thrown if anything fails
	 */
	public void writeAnimation(Animation animation, OutputStream output) throws Exception;

	/**
	 * Check if the animation loader supports the given PolyAnim animation
	 * format version.
	 * 
	 * @param version
	 *            Version string, such as "1.0"
	 * @return true if the given format version is supported
	 */
	public boolean supportsVersion(String version);
}
